Closes #516.

Node had enqueueMany but no accumulator that flushes on size or interval — Python has BatchAccumulator, Java has Batcher<T>. This adds Batcher plus a queue.batcher(name, options?) factory.

using batcher = queue.batcher("ingestLog", { maxSize: 100, maxWaitMs: 500, onError });
batcher.add([line], { priority: 5 });  // returns ids only when this call crossed maxSize
batcher.flush();                       // force
batcher.close();                       // flush remainder + stop the timer (also Symbol.dispose)

Which shape

Java's, not Python's. Java and Node buffer enqueues and flush N jobs through enqueueMany; Python coalesces buffered items into one job whose payload is the list, which needs a worker-side batch-handler contract (per-item results, partial-failure retry) that Node doesn't have. The issue framed the gap as an accumulator over enqueueMany. Python's @task(batch=) coalescing stays Python-only and is worth its own issue.

One place it goes further than Java: add(args, options?) keeps per-entry EnqueueOptions, because Node's enqueueMany takes options per entry where Java's takes one shared set.

Failure and lifecycle

• A failed flush keeps its payloads. flush() splices the buffer before calling enqueueMany — a job.enqueued handler runs synchronously inside it and can re-enter add — and on throw puts the entries back at the head, so submission order holds.
• A caller-triggered flush rethrows. A timed flush has no caller, so it reports to onError (or logs) and re-arms; otherwise entries would strand until the next add.
• The timer is unref'd like every other timer in the SDK, so a partial buffer never holds the process open — and is lost on a bare exit. close() / using is the documented shutdown path.
• Tunables validate to RangeError; add after close throws QueueError.

Docs

New node/api-reference/batching.mdx and node/guides/core/batching.mdx. The API page also documents enqueueMany, which Node had shipped undocumented, and the guide mirrors Java's producer-batching vs dequeue-batchSize framing. The Node block in shared/guides/core/tasks.mdx pointed only at enqueue-options; it now links the new guide.

Testing

12 tests in test/core/batcher.test.ts: size flush, timed flush, close/idempotence, Symbol.dispose, per-entry options, end-to-end run, failed flush retains entries, onError plus timed retry, tunable validation, argument typing, and job.enqueued re-entrancy.

Full Node suite 511 passed / 88 skipped; the 10 test/dashboard/ failures are pre-existing locally (no vite in the dashboard/ workspace). Typecheck and biome clean; docs check:parity and docs build clean.

Summary by CodeRabbit

• New Features

  • Added Node SDK support for producer-side batching with enqueueMany and the Batcher helper.
  • Batches flush automatically when they reach a size limit or wait time, with support for retries and error handling.
  • Added scoped cleanup through close() and using/Symbol.dispose.

• Documentation

  • Added API reference and core guide documentation covering producer and worker batching, configuration, failure handling, and shutdown behavior.
  • Updated navigation and the unreleased changelog.